<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>t Programming</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="kvaser.gif"/></td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_user_guide_kvscript.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">t Programming </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#section_user_guide_kvscript_overview">Overview</a></li>
<li class="level1"><a href="#section_user_guide_kvscript_loading">Load and Unload Script</a></li>
<li class="level1"><a href="#section_user_guide_kvscript_start_stop">Start and Stop script</a></li>
<li class="level1"><a href="#section_user_guide_kvscript_envvar">Environment Variable</a></li>
<li class="level1"><a href="#section_user_guide_kvscript_send_event">Send Event</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="section_user_guide_kvscript_overview"></a>
Overview</h1>
<p>The Kvaser t programming language is event oriented and modeled after C. It can be used to customize the behavior of Kvaser t capable devices. devices.</p>
<p>A t program is invoked via hooks, which are entry points that are executed at the occurrence of certain events. These events can be, for example, the arrival of specific CAN messages, timer expiration, or external input.</p>
<p>Here we will describe how to interact with t programs on a Kvaser device (i.e. loading, starting, stopping) For a complete reference to the t language, see the <a href="https://www.kvaser.com/downloads-kvaser/?utm_source=software&amp;utm_ean=7330130980327&amp;utm_status=latest">Kvaser t Programming Language</a> available from <a href="https://www.kvaser.com/downloads/">www.kvaser.com/downloads</a>.</p>
<h1><a class="anchor" id="section_user_guide_kvscript_loading"></a>
Load and Unload Script</h1>
<p>The first step is to compile your t program into a .txe file, see the <a href="https://www.kvaser.com/downloads-kvaser/?utm_source=software&amp;utm_ean=7330130980327&amp;utm_status=latest">Kvaser t Programming Language</a>. A compiled .txe file may be examined using <a class="el" href="group__t_script.html#ga442c63a2cddbf96ffa0a100e9d9e4283">kvScriptTxeGetData()</a>.</p>
<p>Before starting a t program you need to load it into an available "slot". Some Kvaser devices have multiple slots, and are therefore capable of running multiple programs simultaneously.</p>
<p>To load a script located on the host PC, use <a class="el" href="group__t_script.html#ga14d0df6bf3a9eec3e17bef266b3d9ef9">kvScriptLoadFile()</a>. The canHandle argument is used to determine what channel is set as the default channel for the loaded script. If your canHandle was opened via a device's second channel, the default channel number will be set to 1 (the numbering of channel on the card starts from 0).</p>
<p>To load a script located on the device, use <a class="el" href="group__t_script.html#ga921d35535c61b11893252602d59c8397">kvScriptLoadFileOnDevice()</a>. To copy arbitrary files to and from the the device, use <a class="el" href="canlib_8h.html#a17b1093e1d294442635e5899120c548e">kvFileCopyToDevice()</a> and <a class="el" href="canlib_8h.html#a95f4a1383f8be77e74ff48d8be71aecf">kvFileCopyFromDevice()</a> respectively.</p>
<p><b>Example</b>. The following code fragment shows how to load the compiled script "script0.txe" from PC and "script3.txe" from the SD card, using the channel number "hnd" was opened with as the default channel.</p>
<div class="fragment"><div class="line"><a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7">canStatus</a> stat;</div><div class="line"><a class="code" href="canlib_8h.html#a75f2e3a4c7b1e47c8c6b25b76975b510">CanHandle</a> hnd;</div><div class="line"></div><div class="line">...</div><div class="line"></div><div class="line"><span class="comment">// Load a script that is stored locally (on SD) into script slot 0</span></div><div class="line">stat = <a class="code" href="group__t_script.html#ga921d35535c61b11893252602d59c8397">kvScriptLoadFileOnDevice</a>(hnd, 0, <span class="stringliteral">&quot;script0.txe&quot;</span>);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">  printf(<span class="stringliteral">&quot;Load failed (0), status == %d\n&quot;</span>, stat);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="comment">// Load another script stored on the host (PC) into script slot 3</span></div><div class="line">stat = <a class="code" href="group__t_script.html#ga14d0df6bf3a9eec3e17bef266b3d9ef9">kvScriptLoadFile</a>(hnd, 3, <span class="stringliteral">&quot;script3.txe&quot;</span>);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">  printf(<span class="stringliteral">&quot;Load on device failed (3), status == %d\n&quot;</span>, stat);</div><div class="line">}</div></div><!-- fragment --><p>To unload a stopped script, use <a class="el" href="group__t_script.html#ga5281c6fb6a81282850d8022293fd92d5">kvScriptUnload()</a>.</p>
<p>You may use <a class="el" href="canlib_8h.html#a6f7e3b5d2faf2556a40ec7818cd74c47">kvFileGetCount()</a>, and <a class="el" href="canlib_8h.html#ad6ffe54a4c22dbdde855e5c8dd0634fa">kvFileGetName()</a> to examine files located on the Kvaser device, and <a class="el" href="canlib_8h.html#a5430e6449f86509bb380672ee4183cc9">kvFileDelete()</a> to delete a specific file.</p>
<dl class="section note"><dt>Note</dt><dd>Not all Kvaser devices support storing t programs and other files locally on the device (i.e. USBcan Pro 2xHS v2). Please refer to your device's User Guide for more information. All User Guides may be downloaded from <a href="https://www.kvaser.com/download/#?categories=documentation">www.kvaser.com/downloads</a></dd></dl>
<h1><a class="anchor" id="section_user_guide_kvscript_start_stop"></a>
Start and Stop script</h1>
<p>To start a previously loaded t program, use <a class="el" href="group__t_script.html#gabcba6dfd72c06214b4bac2059846b4d0">kvScriptStart()</a>. You may stop a running script using <a class="el" href="group__t_script.html#gaf07b9d776a3682f0093d1cfe4e26f31c">kvScriptStop()</a>. To examine the status of a slot (i.e. if the slot is free or have a program loaded or running), use <a class="el" href="group__t_script.html#gadcbe8f74ee454f27f22f9645ce0a144f">kvScriptStatus()</a>.</p>
<p><b>Example</b>. Starting and stopping scripts loaded in slot 0 and 3. </p><div class="fragment"><div class="line"><span class="comment">// Start script in slot 0</span></div><div class="line">stat = <a class="code" href="group__t_script.html#gabcba6dfd72c06214b4bac2059846b4d0">kvScriptStart</a>(hnd, 0);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">  printf(<span class="stringliteral">&quot;Start failed (0), status == %d\n&quot;</span>, stat);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="comment">// Start script in slot 3</span></div><div class="line">stat = <a class="code" href="group__t_script.html#gabcba6dfd72c06214b4bac2059846b4d0">kvScriptStart</a>(hnd, 3);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">  printf(<span class="stringliteral">&quot;Start failed (3), status == %d\n&quot;</span>, stat);</div><div class="line">}</div><div class="line"></div><div class="line">...</div><div class="line"></div><div class="line"><span class="comment">// Try to stop script in slot 3</span></div><div class="line">stat = <a class="code" href="group__t_script.html#gaf07b9d776a3682f0093d1cfe4e26f31c">kvScriptStop</a>(hnd, 3, <a class="code" href="canlib_8h.html#a6e2559022254e1e5f797da3187e7a176">kvSCRIPT_STOP_NORMAL</a>);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">  printf(<span class="stringliteral">&quot;Stop (3) failed, status == %d\n&quot;</span>, stat);</div><div class="line"></div><div class="line">  <span class="comment">// For some reason this failed (script is busy?) so we request it to stop.</span></div><div class="line"></div><div class="line">  <span class="comment">// Note that this is an request and that the script might still be running</span></div><div class="line">  <span class="comment">// when this call returns.</span></div><div class="line"></div><div class="line">  stat = <a class="code" href="group__t_script.html#gaf07b9d776a3682f0093d1cfe4e26f31c">kvScriptStop</a>(hnd, 3, <a class="code" href="canlib_8h.html#aa4c1f532f113deb0fc86e12fc50ff184">kvSCRIPT_STOP_FORCED</a>);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Forced stop failed (3), status == %d\n&quot;</span>, stat);</div><div class="line">  }</div><div class="line">  Sleep(100); <span class="comment">// make sure it has stopped.</span></div><div class="line">}</div><div class="line"></div><div class="line">...</div></div><!-- fragment --><h1><a class="anchor" id="section_user_guide_kvscript_envvar"></a>
Environment Variable</h1>
<p>To communicate between the PC and your t program, you can use t Environment Variables (Envvar). The first step is to get a handle to your Envvar using <a class="el" href="group__t_script.html#gac090487e06584e640350e9a2364715c6">kvScriptEnvvarOpen()</a>.</p>
<p>Depending of the type of the Envvar, you may now examine the value using <a class="el" href="group__t_script.html#gacf9775ec635485786a4afb3cb77ce94e">kvScriptEnvvarGetInt()</a>, <a class="el" href="group__t_script.html#gafee8ff7e33041bee5f523115aae7f59e">kvScriptEnvvarGetFloat()</a> and <a class="el" href="group__t_script.html#ga5cbb37e43a2e24358c63295fedfe06a3">kvScriptEnvvarGetData()</a>. The size of the "Data" Envvar is set by the user but can be max <a class="el" href="group__t_script.html#gafe38fc6634a1743f404001def0ffa392">kvScriptGetMaxEnvvarSize()</a> bytes.</p>
<p>To change the value of the Envvar, use <a class="el" href="group__t_script.html#gaef0cffb28882fa9a731cda884ea8332c">kvScriptEnvvarSetInt()</a>, <a class="el" href="group__t_script.html#ga0e1f89bb27cb2041643e9e97efd47839">kvScriptEnvvarSetFloat()</a> and <a class="el" href="group__t_script.html#ga5d81bb016783417bbb90cee739fed5a4">kvScriptEnvvarSetData()</a> respectively.</p>
<p>Use <a class="el" href="group__t_script.html#ga30f88cbfc588c801f8bf4c81c094875c">kvScriptEnvvarClose()</a> to free up memory when done handling the Envvar</p>
<p><b>Example</b>. The following code fragment shows how to use environment variables, Envvars for communication between a PC and a script.</p>
<div class="fragment"><div class="line"><a class="code" href="canlib_8h.html#a75f2e3a4c7b1e47c8c6b25b76975b510">CanHandle</a> hnd;</div><div class="line"><a class="code" href="canlib_8h.html#ac12ca60f6d6e18d9bd29acc00c8ea2ff">kvEnvHandle</a> env_hnd;</div><div class="line"><a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7">canStatus</a> stat;</div><div class="line"><span class="keywordtype">int</span> envvar_size;</div><div class="line"><span class="keywordtype">int</span> envvar_type;</div><div class="line"></div><div class="line"><span class="keywordtype">int</span>   int_val   = 0;</div><div class="line"><span class="keywordtype">float</span> float_val = 0;</div><div class="line"><span class="keywordtype">char</span> buffer_val[10] = {0,0,0,0,0,0,0,0,0,0};</div><div class="line"></div><div class="line">...</div><div class="line"></div><div class="line"><span class="comment">// Open an int envvar called &quot;ev1_int&quot; and set its value to 55</span></div><div class="line">env_hnd = <a class="code" href="group__t_script.html#gac090487e06584e640350e9a2364715c6">kvScriptEnvvarOpen</a>(hnd, <span class="stringliteral">&quot;ev1_int&quot;</span>, &amp;envvar_type, &amp;envvar_size);</div><div class="line"><span class="keywordflow">if</span> (env_hnd &lt; 0) {</div><div class="line">  printf(<span class="stringliteral">&quot;Open failed, env_hnd = %d\n&quot;</span>, env_hnd);</div><div class="line">} <span class="keywordflow">else</span> {</div><div class="line">  printf(<span class="stringliteral">&quot;envvar_size = %d, envvar_type = %d\n&quot;</span>, envvar_size, envvar_type);</div><div class="line"></div><div class="line">  stat = <a class="code" href="group__t_script.html#gaef0cffb28882fa9a731cda884ea8332c">kvScriptEnvvarSetInt</a>(env_hnd, 55);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, stat = %d\n&quot;</span>, stat);</div><div class="line">  }</div><div class="line"></div><div class="line">  <span class="comment">// Read back the value of &quot;ev1_int&quot; and close.</span></div><div class="line">  stat = <a class="code" href="group__t_script.html#gacf9775ec635485786a4afb3cb77ce94e">kvScriptEnvvarGetInt</a>(env_hnd, &amp;int_val);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, stat = %d\n&quot;</span>, stat);</div><div class="line">  } <span class="keywordflow">else</span> {</div><div class="line">    printf(<span class="stringliteral">&quot;int_val = %d\n&quot;</span>, int_val);</div><div class="line">  }</div><div class="line"></div><div class="line">  stat = <a class="code" href="group__t_script.html#ga30f88cbfc588c801f8bf4c81c094875c">kvScriptEnvvarClose</a>(env_hnd);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, stat = %d\n&quot;</span>, stat);</div><div class="line">  }</div><div class="line">}</div><div class="line"></div><div class="line"></div><div class="line"><span class="comment">// Open a float envvar called &quot;ev1_float&quot; and set its value to 55.55</span></div><div class="line">env_hnd = <a class="code" href="group__t_script.html#gac090487e06584e640350e9a2364715c6">kvScriptEnvvarOpen</a>(hnd, <span class="stringliteral">&quot;ev1_float&quot;</span>, &amp;envvar_type, &amp;envvar_size);</div><div class="line"><span class="keywordflow">if</span> (env_hnd &lt; 0) {</div><div class="line">  printf(<span class="stringliteral">&quot;Open failed, env_hnd = %d\n&quot;</span>, env_hnd);</div><div class="line">} <span class="keywordflow">else</span> {</div><div class="line">  printf(<span class="stringliteral">&quot;envvar_size = %d, envvar_type = %d\n&quot;</span>, envvar_size, envvar_type);</div><div class="line"></div><div class="line">  stat = <a class="code" href="group__t_script.html#ga0e1f89bb27cb2041643e9e97efd47839">kvScriptEnvvarSetFloat</a>(env_hnd, (<span class="keywordtype">float</span>)55.55);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, stat = %d\n&quot;</span>, stat);</div><div class="line">  }</div><div class="line"></div><div class="line">  <span class="comment">// Read back the value of &quot;ev1_int&quot; and close.</span></div><div class="line">  stat = <a class="code" href="group__t_script.html#gafee8ff7e33041bee5f523115aae7f59e">kvScriptEnvvarGetFloat</a>(env_hnd, &amp;float_val);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, stat == %d\n&quot;</span>, stat);</div><div class="line">  }</div><div class="line">  printf(<span class="stringliteral">&quot;float_val = %f\n&quot;</span>, float_val);</div><div class="line"></div><div class="line">  stat = <a class="code" href="group__t_script.html#ga30f88cbfc588c801f8bf4c81c094875c">kvScriptEnvvarClose</a>(env_hnd);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, stat = %d\n&quot;</span>, stat);</div><div class="line">  }</div><div class="line">}</div><div class="line"></div><div class="line"></div><div class="line"><span class="comment">// Open a buffer envvar called &quot;ev1_buffer&quot; and set its value to &quot;&quot;hello1234&quot;&quot;</span></div><div class="line">env_hnd = <a class="code" href="group__t_script.html#gac090487e06584e640350e9a2364715c6">kvScriptEnvvarOpen</a>(hnd, <span class="stringliteral">&quot;ev1_float&quot;</span>, &amp;envvar_type, &amp;envvar_size);</div><div class="line"><span class="keywordflow">if</span> (env_hnd &lt; 0) {</div><div class="line">  printf(<span class="stringliteral">&quot;Open failed, env_hnd = %d\n&quot;</span>, env_hnd);</div><div class="line">} <span class="keywordflow">else</span> {</div><div class="line">  printf(<span class="stringliteral">&quot;envvar_size = %d, envvar_type = %d\n&quot;</span>, envvar_size, envvar_type);</div><div class="line"></div><div class="line">  <span class="comment">// Set value, starting at index 0 in buffer and length 10</span></div><div class="line">  stat = <a class="code" href="group__t_script.html#ga5d81bb016783417bbb90cee739fed5a4">kvScriptEnvvarSetData</a>(env_hnd, <span class="stringliteral">&quot;hello1234&quot;</span>, 0, 10);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, stat = %d\n&quot;</span>, stat);</div><div class="line">  }</div><div class="line"></div><div class="line">  <span class="comment">// Read back the value of &quot;ev1_buffer&quot; and close.</span></div><div class="line">  stat = <a class="code" href="group__t_script.html#ga5cbb37e43a2e24358c63295fedfe06a3">kvScriptEnvvarGetData</a>(env_hnd, buffer_val, 0, 10);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, stat = %d\n&quot;</span>, stat);</div><div class="line">  }</div><div class="line">  printf(<span class="stringliteral">&quot;buffer_val = %s\n&quot;</span>, buffer_val);</div><div class="line"></div><div class="line">  stat = <a class="code" href="group__t_script.html#ga30f88cbfc588c801f8bf4c81c094875c">kvScriptEnvvarClose</a>(env_hnd);</div><div class="line">  <span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, stat = %d\n&quot;</span>, stat);</div><div class="line">  }</div><div class="line">}</div></div><!-- fragment --><h1><a class="anchor" id="section_user_guide_kvscript_send_event"></a>
Send Event</h1>
<p>You may trigger the "on key" hook by sending the event <a class="el" href="canlib_8h.html#a84d68bc3e337a19087053fb21e79d1f3">kvEVENT_TYPE_KEY</a> to a script using <a class="el" href="group__t_script.html#ga1ab0e65f93389fddf3cd7531a96a5662">kvScriptSendEvent()</a>.</p>
<p><b>Example</b>. The following code fragment shows how to send a key to a script.</p>
<div class="fragment"><div class="line"><a class="code" href="canlib_8h.html#a75f2e3a4c7b1e47c8c6b25b76975b510">CanHandle</a> hnd;</div><div class="line"><a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7">canStatus</a> stat;</div><div class="line"><span class="keywordtype">int</span> slot_number;</div><div class="line"></div><div class="line">...</div><div class="line"></div><div class="line"><span class="comment">// Send key &#39;a&#39; to scripts running in slot 0...3</span></div><div class="line">for (slot_number = 0; slot_number &lt; 4; slot_number++) {</div><div class="line">  stat = <a class="code" href="group__t_script.html#ga1ab0e65f93389fddf3cd7531a96a5662">kvScriptSendEvent</a>(hnd, slot_number, <a class="code" href="canlib_8h.html#a84d68bc3e337a19087053fb21e79d1f3">kvEVENT_TYPE_KEY</a>, <span class="charliteral">&#39;a&#39;</span>, 0);</div><div class="line">}</div></div><!-- fragment --> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.13-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="page_canlib.html">CAN bus API (CANlib)</a></li>
    <li class="footer"> (canlib 5.38) Tue Feb 15 2022</li>
  </ul>
</div>
</body>
</html>
